[][src]Crate surf

surf the web.

Surf is a friendly HTTP client built for casual Rustaceans and veterans alike. It's completely modular, and built directly for async/await. Whether it's a quick script, or a cross-platform SDK, Surf will make it work.

  • Multi-platform out of the box
  • Extensible through a powerful middleware system
  • Reuses connections through the Client interface
  • Fully streaming requests and responses
  • TLS/SSL enabled by default
  • Swappable HTTP backends
  • HTTP/2 enabled by default

Examples

let mut res = surf::get("https://httpbin.org/get").await?;
dbg!(res.body_string().await?);

It's also possible to skip the intermediate Response, and access the response type directly.

dbg!(surf::get("https://httpbin.org/get").recv_string().await?);

Both sending and receiving JSON is real easy too.

#[derive(Deserialize, Serialize)]
struct Ip {
    ip: String
}

let uri = "https://httpbin.org/post";
let data = &Ip { ip: "129.0.0.1".into() };
let res = surf::post(uri).body_json(data)?.await?;
assert_eq!(res.status(), 200);

let uri = "https://api.ipify.org?format=json";
let Ip { ip } = surf::get(uri).recv_json().await?;
assert!(ip.len() > 10);

And even creating streaming proxies is no trouble at all.

let reader = surf::get("https://img.fyi/q6YvNqP").await?;
let res = surf::post("https://box.rs/upload").body(reader).await?;

Features

The following features are available.

  • native-client (default): use curl on the server and window.fetch in the browser.
  • middleware-logger (default): enables logging requests and responses using a middleware.
  • curl-client: use curl (through isahc) as the HTTP backend.
  • hyper-client: use hyper as the HTTP backend.
  • wasm-client: use window.fetch as the HTTP backend.

Re-exports

pub use http;
pub use mime;
pub use url;

Modules

headers

HTTP Headers.

middleware

Middleware types

Structs

Client

An HTTP client, capable of creating new Requests.

Request

An HTTP request, returns a Response.

Response

An HTTP response, returned by Request.

Functions

connect

Perform a one-off CONNECT request.

delete

Perform a one-off DELETE request.

get

Perform a one-off GET request.

head

Perform a one-off HEAD request.

options

Perform a one-off OPTIONS request.

patch

Perform a one-off PATCH request.

post

Perform a one-off POST request.

put

Perform a one-off PUT request.

trace

Perform a one-off TRACE request.

Type Definitions

Exception

A generic error type.